feat(policy): rag-policy package — PolicyEngine PDP + coverage linter (Step 1.1c) - #46

Summary

Step 1.1c of the Phase 1 architecture-refactor window. Lands the
Policy Decision Point ADR-0005 calls for: a single auditable surface
that every retrieval / ingest / egress code path consults, plus a CI
linter that fails when a new governance-relevant call site bypasses it.

• New workspace package packages/policy/ (rag-policy v0.1.0,
  import root rag_policy). Depends on rag-core + rag-observability only
  (matches the dependency graph in CLAUDE.md).
• PolicyEngine ABC — async evaluate(ctx, decision, subject) -> PolicyResult and async filter_pushdown(ctx, decision) -> FilterExpr.
• NoopPolicyEngine — always-ALLOW reference impl; filter_pushdown
  still emits And(Eq("tenant_id", str(ctx.tenant_id))) so retrieval
  backends cannot cross-tenant leak even with the noop loaded.
• PolicyWriter facade (mirrors AuditWriter) — delegates to the
  engine and emits a policy.decision structured-log entry via
  rag_observability.logging. Consumers should reach for the writer.
• PolicyDecision enum: read_chunk / ingest_doc / egress_text
  / quota_check / rate_limit / execute_plan.
• PolicyResult frozen union (allow / deny(reason) /
  transform(subject)) with predicate helpers.
• FilterExpr mini-language (Eq, AnyIn, And, Or, Not,
  TrueExpr) — discriminated-union of frozen Pydantic models, returned
  by filter_pushdown and consumed by retrieval backends.
• Coverage linter tests/policy/coverage.py greps for
  retrieve_ids / hydrate / bulk_index / stream_index /
  bulk_embed / .complete( call sites without an adjacent
  PolicyEngine / PolicyWriter marker. File-allowlist at the top;
  consumers (gateway, ingest) shrink the allowlist as they wire the PDP
  in. A future Step 1.1f tightens the linter from file-allowlist to
  call-pattern matching.

Step 6.4 (ACL egress verifier as a second layer) is rendered redundant
by this PDP — see ADR-0005. The TRACKER entry for 6.4 will flip to
"Superseded by ADR-0005" in the Phase 6 refactor pass.

Documentation

• New docs/reference/rag-policy.md
  (Overview / Usage / Internals / Extension points).
• docs/README.md index updated.
• ADR-0005 and docs/architecture/policy-engine.md already describe the
  shipped shape — no changes needed there.

Test plan

• `uv run ruff check . && uv run ruff format --check .` — clean
• `uv run mypy packages/ apps/gateway/` — 83 source files, no issues
  (+7 from Step 1.1b)
• `uv run python scripts/check_logging.py` — RAG001 clean
• `uv run pytest tests/ packages/ --ignore=tests/integration -x -q` —
  528 passed, 1 skipped (20 new conformance + 1 coverage linter)
• Coverage linter passes against current tree (allowlist correct
  for noop + abstracts + real backends).

TRACKER housekeeping rolled in

• Step 1.1c flipped to ✅; Phase 1 done-count bumped (3 → 4); Next
  action set to 1.1d — Pipeline + Batcher primitives.
• PR history table: added rows for #44 (Step 1.1a) and #45 (Step 1.1b)
  which were missed when those merged.

🤖 Generated with Claude Code